<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Cross-Reference Tables Reference &mdash; Geraldo Reports Documentation v0.4.1-stable documentation</title>
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '',
        VERSION:     '0.4.1-stable',
        COLLAPSE_MODINDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="top" title="Geraldo Reports Documentation v0.4.1-stable documentation" href="index.html" />
    <link rel="next" title="Generators Reference" href="generators.html" />
    <link rel="prev" title="Barcodes Reference" href="barcodes.html" /> 
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="generators.html" title="Generators Reference"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="barcodes.html" title="Barcodes Reference"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">Geraldo Reports Documentation v0.4.1-stable documentation</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="cross-reference-tables-reference">
<h1>Cross-Reference Tables Reference<a class="headerlink" href="#cross-reference-tables-reference" title="Permalink to this headline">¶</a></h1>
<p><strong>New on 0.4</strong></p>
<p>According to [Wikipedia](<a class="reference external" href="http://en.wikipedia.org/wiki/Cross_reference">http://en.wikipedia.org/wiki/Cross_reference</a>):</p>
<blockquote>
A cross-reference (noun) is an instance within a document which refers to
related or synonymous information elsewhere, usually within the same work. To
cross-reference or to cross-refer (verb) is to make such connections.
The term &#8220;cross-reference&#8221; is often abbreviated as x-ref, xref, or, in
computer science, XR. Cross-referencing is usually employed to either verify
claims made by an author or to link to another piece of work that is of
related interest.</blockquote>
<p><strong>Translating to practical life</strong></p>
<p>Cross-reference is when you have much data and want to cross the relation between
two fields to get a third value.</p>
<p><strong>Example</strong></p>
<p>If you have an ERP system that supports many stores, selling many products, you
can to need a report with &#8220;Product Sellings per Store&#8221;, what means you have a
bunch of data and 3 entities to base on: Products, Sellings and Stores, and you
will have rows for Products, columns for Stores and the cells with an aggregation
value about the Sellings that cross with a Product AND a Store, like the
following:</p>
<div class="highlight-python"><pre>          | Store 1 | Store 2 | Store 3 | Average
--------------------------------------------------
Product 1 |   159   |     0   |   130   |    96
Product 1 |    49   |    20   |    30   |    30
Product 1 |   181   |   230   |    27   |   146
--------------------------------------------------
  Totals  |   389   |   250   |   187   |   275</pre>
</div>
<p>As you probably noted, the first column of rows is the list of a coordinage X
(the Products), the first row of columnss is the list of a coordinate Y (the
Stores) and the cells are the crossed relation between Products and Stores
(probably the count of sellings of each Product on each Store). The latest column
is the average aggregation of cells of the same row, and the latest row is the
average of cells of same column.</p>
<div class="section" id="crossreferencematrix">
<h2>CrossReferenceMatrix<a class="headerlink" href="#crossreferencematrix" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="geraldo.cross_reference.CrossReferenceMatrix">
<em class="property">class </em><tt class="descclassname">geraldo.cross_reference.</tt><tt class="descname">CrossReferenceMatrix</tt><a class="headerlink" href="#geraldo.cross_reference.CrossReferenceMatrix" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>Path: <strong>geraldo.CrossReferenceMatrix</strong></p>
<p><strong>The Solution</strong></p>
<p>As you can realize, this is not an easy job, because you never know how many
columns you will have, and there are many ways to collect cross-reference data.</p>
<p>Some RDBMS&#8217;s offers <em>out of box</em> ways to get a cross-reference among three
fields in a select, but this is not only limited but is also not a definitive
solution, because even if you have the matrix of data, you still have to
prepare all elements on the report you are going to print.</p>
<p>The solution on Geraldo is the class &#8216;geraldo.cross_reference.CrossReferenceMatrix&#8217;.</p>
<p>To instantiate this class, you must inform the objects list (not necessarily a
matrix, because you can just give a Django queryset, or a list of dictionaries)
and the names of the X and Y attributes (<strong>row_attribute</strong> and <strong>col_attribute</strong>).</p>
<p>Once you create that instance, you can call many methods from it to get aggregated
values, giving the third attribute you want to aggregate, and the filter for row
and column directions.</p>
<p>This instance can be used out of Geraldo&#8217;s functions, like a template, e-mails,
text files, whatever, it is not dependent on reports to work.</p>
<p><strong>Methods</strong></p>
<ul>
<li><p class="first"><strong>__init__(objects_list, rows_attribute, cols_attribute)</strong></p>
<blockquote>
<p>When you make an instance of <strong>CrossReferenceMatrix</strong>, you must inform the objects
list and the attributes to cross: rows_attribute (X) and cols_attribute (Y).</p>
</blockquote>
</li>
<li><p class="first"><strong>rows()</strong></p>
<blockquote>
<p>Returns the values of row attribute in objects list, that means you get the list
of rows on the matrix.</p>
</blockquote>
</li>
<li><p class="first"><strong>cols()</strong></p>
<blockquote>
<p>Returns the values of column attribute on objects list, that means you get the list
of columns on the matrix.</p>
</blockquote>
</li>
<li><p class="first"><strong>values(cell, row=RANDOM_ROW_DEFAULT, col=RANDOM_COL_DEFAULT)</strong></p>
<blockquote>
<p>Returns the values (a list of them) crossed between a row and a column. If you just
let the argument &#8216;row&#8217; or &#8216;col&#8217; with default value, it will get all values according
to the filter you informed (i.e. if you just informed the &#8216;col&#8217;, you will get all
values for that col, in the sequence of the available rows).</p>
<p>This method is used by all of the others below.</p>
</blockquote>
</li>
<li><p class="first"><strong>max(cell, row=RANDOM_ROW_DEFAULT, col=RANDOM_COL_DEFAULT)</strong></p>
<blockquote>
<p>As same as method &#8216;values&#8217;, but this find the maximum value for that relation and
returns it.</p>
</blockquote>
</li>
<li><p class="first"><strong>min(cell, row=RANDOM_ROW_DEFAULT, col=RANDOM_COL_DEFAULT)</strong></p>
<blockquote>
<p>As same as method &#8216;max&#8217;, but returns the minimum value of them.</p>
</blockquote>
</li>
<li><p class="first"><strong>sum(cell, row=RANDOM_ROW_DEFAULT, col=RANDOM_COL_DEFAULT)</strong></p>
<blockquote>
<p>As same as method &#8216;max&#8217;, but returns the sum of found values.</p>
</blockquote>
</li>
<li><p class="first"><strong>avg(cell, row=RANDOM_ROW_DEFAULT, col=RANDOM_COL_DEFAULT)</strong></p>
<blockquote>
<p>As same as method &#8216;max&#8217;, but returns the average of found values.</p>
</blockquote>
</li>
<li><p class="first"><strong>count(cell, row=RANDOM_ROW_DEFAULT, col=RANDOM_COL_DEFAULT)</strong></p>
<blockquote>
<p>As same as method &#8216;max&#8217;, but returns the count of found values.</p>
</blockquote>
</li>
<li><p class="first"><strong>distinct_count(cell, row=RANDOM_ROW_DEFAULT, col=RANDOM_COL_DEFAULT)</strong></p>
<blockquote>
<p>As same as method &#8216;count&#8217;, but returns the count of not redundant values.</p>
</blockquote>
</li>
<li><p class="first"><strong>first(cell, row=RANDOM_ROW_DEFAULT, col=RANDOM_COL_DEFAULT)</strong></p>
<blockquote>
<p>Just returns the first value found for the relation.</p>
</blockquote>
</li>
<li><p class="first"><strong>last(cell, row=RANDOM_ROW_DEFAULT, col=RANDOM_COL_DEFAULT)</strong></p>
<blockquote>
<p>As same as method &#8216;first&#8217;, but returns the last value.</p>
</blockquote>
</li>
<li><p class="first"><strong>matrix(cell, func=&#8217;values&#8217;)</strong></p>
<blockquote>
<p>Returns a matrix with rows and columns with cross table values (including
headers).</p>
</blockquote>
</li>
</ul>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
            <h3><a href="index.html">Table Of Contents</a></h3>
            <ul>
<li><a class="reference external" href="">Cross-Reference Tables Reference</a><ul>
<li><a class="reference external" href="#crossreferencematrix">CrossReferenceMatrix</a></li>
</ul>
</li>
</ul>

            <h4>Previous topic</h4>
            <p class="topless"><a href="barcodes.html"
                                  title="previous chapter">Barcodes Reference</a></p>
            <h4>Next topic</h4>
            <p class="topless"><a href="generators.html"
                                  title="next chapter">Generators Reference</a></p>
            <h3>This Page</h3>
            <ul class="this-page-menu">
              <li><a href="_sources/cross-reference.txt"
                     rel="nofollow">Show Source</a></li>
            </ul>
          <div id="searchbox" style="display: none">
            <h3>Quick search</h3>
              <form class="search" action="search.html" method="get">
                <input type="text" name="q" size="18" />
                <input type="submit" value="Go" />
                <input type="hidden" name="check_keywords" value="yes" />
                <input type="hidden" name="area" value="default" />
              </form>
              <p class="searchtip" style="font-size: 90%">
              Enter search terms or a module, class or function name.
              </p>
          </div>
          <script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="generators.html" title="Generators Reference"
             >next</a> |</li>
        <li class="right" >
          <a href="barcodes.html" title="Barcodes Reference"
             >previous</a> |</li>
        <li><a href="index.html">Geraldo Reports Documentation v0.4.1-stable documentation</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
      &copy; Copyright 2009-2010, Marinho Brandao.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.3.
    </div>
  </body>
</html>